sound_pool object

This method will play a sound that can move around according to the listener and source positions on a 1d grid, allowing you to specify various starting settings for the sound, as well as a range in which the sound should remain with the listener.

int play_extended_1d(string filename, int listener_x, int sound_x, int left_range, int right_range, bool looping, double offset, float start_pan, float start_volume, float start_pitch, bool persistent=false)

Parameters:
filename
The filename to play.
listener_x
The position of the listener on the grid.
sound_x
The position of the source object on the grid.
left_range
The leftmost position from the centre of the source where the sound should remain with the listener.
right_range
The rightmost position from the centre of the source where the sound should remain with the listener.
looping
A boolean specifying whether the sound should loop or not.
offset
The point in the sound file where playback should begin, in milliseconds.
start_pan
The starting pan of the sound.
start_volume
The starting volume of the sound.
start_pitch
The starting pitch of the sound.
persistent
An optional boolean specifying whether the sound should be persistent or not, meaning whether or not it should be automatically cleaned up after playback has finished. If this argument is not given, false is the default which means that the sound does get cleaned up.

Return value:
Returns the slot where the sound is stored in the pool, -1 on error, or -2 if the sound is out of earshot.

Remarks:
This method is useful for playing sounds specific to the game objects and characters, for example monsters, health boosters, teleporters, etc.

The range of the sound determines how far the listener can move before they move away from the source. This, for example, enables you to have a river or an impassable wall of fire or electricity, etc.

All the position calculations will be done relative to the values you specify for start_pan and start_volume. The pitch will simply be set to the value specified and will then remain unchanged.

A sound that is created with the persistent flag will not be cleaned up after it has finished playing, which otherwise is the default behavior. Instead, an explicit call must be made to destroy the sound. This is useful for non-looping sounds that you wish to be able to reliably manipulate with any of the functions that use slots to identify a particular sound. When set as persistent, a sound slot is guaranteed to stay valid regardless of playback status. This also means that you must be sure to destroy it when it is no longer in use, as that slot will otherwise be locked and not available for reuse by new sounds.

Example:
#include "sound_pool.bgt"

sound_pool sound_environment;
timer walk_timer;

int player_position;
int step;

const string sound_extension=".wav";

const int left=-1;
const int right=1;

const int boundary=200;

void main()
{
show_game_window("sound_pool test");
sound_environment.max_distance=70;
for(int counter=1; counter<15; counter++)
{
sound_environment.play_extended_1d("sounds/sound"+counter+sound_extension, 0, random(0, boundary), 5, 5, true, 500, 0, -1, 90, false);
}
while(true)
{
check_input();
wait(5);
}
}

void check_input()
{
if((key_down(KEY_LMENU))&&(key_pressed(KEY_F4)))
{
exit();
}
if(key_down(KEY_LEFT))
{
walk(left);
}
if(key_down(KEY_RIGHT))
{
walk(right);
}
}

void walk(int direction)
{
if((direction<=left)&&(player_position<=0))
{
return;
}
if((direction>=right)&&(player_position>=boundary))
{
return;
}
if(walk_timer.elapsed<350)
{
return;
}
step++;
if(step>6)
{
step=1;
}
walk_timer.restart();
player_position+=direction;
sound_environment.play_stationary("sounds/steps/"+step+sound_extension, false);
sound_environment.update_listener_1d(player_position);
}